Skip to content

feat(api): document public API authentication#1038

Open
KonradStanski wants to merge 3 commits intosourcebot-dev:mainfrom
KonradStanski:konrad/public-api-auth
Open

feat(api): document public API authentication#1038
KonradStanski wants to merge 3 commits intosourcebot-dev:mainfrom
KonradStanski:konrad/public-api-auth

Conversation

@KonradStanski
Copy link
Contributor

@KonradStanski KonradStanski commented Mar 24, 2026 •
edited by coderabbitai bot
Loading

Summary

This documents authentication for the public Sourcebot API in the generated OpenAPI spec and Mintlify docs.

Changes:

  • add public API auth metadata to the OpenAPI document
  • document supported auth schemes for external clients
  • clarify auth usage in the API reference intro docs
  • remove the stale hard-coded version example from the version schema

Details

The spec now documents these auth paths:

  • X-Sourcebot-Api-Key: sbk_...
  • Authorization: Bearer sbk_...
  • Authorization: Bearer sboa_... for EE OAuth access tokens

The API reference docs now lead users to the runtime spec endpoint and explain how auth works for public API consumers.

Testing

  • yarn openapi:generate

Notes

  • The public API may allow anonymous access depending on instance configuration, so the spec reflects that auth can be optional on some deployments.
  • SSE responses are still documented as text/event-stream; OpenAPI does not model typed SSE frames especially well.

Closes #101

Summary by CodeRabbit

  • Documentation
    • Added API authentication guide: how to create/use API keys or bearer tokens, and OAuth support on EE instances.
    • Clarified instance-dependent auth behavior, including possible anonymous access.
    • Published API security schemes and global auth options to improve tooling and client generation.
    • Removed an example value from the public version response schema.

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Mar 24, 2026 •
edited
Loading

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5336b23b-ed2d-40d9-8ca5-3a56523f4dcd

📥 Commits

Reviewing files that changed from the base of the PR and between d07be8c and 9324e51.

📒 Files selected for processing (1)
  • docs/api-reference/sourcebot-public.openapi.json
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/api-reference/sourcebot-public.openapi.json

Walkthrough

Updated the public OpenAPI document, generation code, and docs to declare bearer and API-key authentication (with a top-level security matrix allowing bearer, API key, or anonymous), added operationId values to seven public endpoints, and removed an example from the version response schema.

Changes

Cohort / File(s) Summary
OpenAPI spec
docs/api-reference/sourcebot-public.openapi.json		 Added top-level security entries (allow bearerAuth, sourcebotApiKey, or anonymous); added components.securitySchemes for bearerAuth (HTTP bearer) and sourcebotApiKey (header X-Sourcebot-Api-Key); removed example on PublicVersionResponse.version; added operationIds for several operations.
OpenAPI generation code
packages/web/src/openapi/publicApiDocument.ts		 Assembled typed components including securitySchemes, injected global security matrix into the generated document, extended info.description with instance-dependent auth details, and added operationId values to public paths (search, streamSearch, listRepositories, getVersion, getFileSource, getFileTree, listFiles).
Schema definitions
packages/web/src/openapi/publicApiSchemas.ts		 Removed the example metadata from the version field in publicVersionResponseSchema (no shape/signature change).
API docs
docs/docs/api-reference/overview.mdx		 Added authentication guidance: create API keys and send via X-Sourcebot-Api-Key or Authorization: Bearer; noted some instances may allow anonymous access and EE instances may accept OAuth bearer tokens with sboa_... prefix.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely describes the main change: adding documentation for public API authentication to the OpenAPI spec.
Linked Issues check ✅ Passed The PR directly addresses issue #101's core objectives by documenting the REST API surface, defining authentication schemes, and providing usage examples.
Out of Scope Changes check ✅ Passed All changes are directly related to documenting API authentication and specification—no unrelated modifications detected.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[FR] Sourcebot REST API support

2 participants

@KonradStanski @brendan-kellam